                         _ ____             __   _  _   
     _ __ ___  _ __ ___ | |___ \ _ __ ___  / /_ | || |  
    | '_ ` _ \| '_ ` _ \| | __) | '_ ` _ \| '_ \| || |_ 
    | | | | | | | | | | | |/ __/| | | | | | (_) |__   _|
    |_| |_| |_|_| |_| |_|_|_____|_| |_| |_|\___/   |_|  
         by messiaen (aka frauber)            [v0.1b]
 
        http://sites.google.com/site/messiaen64/Home
               www.youtube.com/user/frauber

/-/-/-/- What is it? /-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/

   mml2m64 is an experimental .mml importer that produces custom music in the Mario 64 
and Zelda 64 sequence format. The main importer module is built from Addmusic's (revX)
MML parser, so big thanks to whoever wrote that program. You can download Addmusic
binaries, source code and documentation at http://www.smwcentral.net.

    The importer is to be used along a MIDI -> MML conversion tool, such as tinymm or
mid2mml, both of which can be download at SMW Central. Afterwards, you can insert the 
custom music using the sequence inserter tool included in this package, which replaces
the original  Mario 64 sequences files with your custom music.

    This package also includes a few more music-related tools, such as sequence rippers
for Mario and Zelda 64 as well as parsing utilities that can display all the sequence 
content. A description of all the tools included and their usage can be found below in
this document. All sources are in the src folder except mml2m64, because it will be
cleared and partly rewritten for a next release.


/-/-/-/-/- What is the mml format? /-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/

   Music Macro Language (MML) is a text-based format suitable for simple sequenced music.
The basic format is very simple and consist of the following fundamental syntax:

cdefgabc = pitches followed by lenght (1 = whole note, 2 = half, 4 = quarter and so on)
+/#      = sharp note (c+ = C#)
-        = flat note (b- = Bb)
r        = rest, followed by time
o        = octave setting
<        = lower octave
>        = raise octave
l        = default note value (l8 c d e f g is the same as c8 d8 e8 f8 g8)

   This is the syntax adopted by Addmusic and followed by mml2m64. There are also some
custom commands which will be covered briefly. You can good overviews of the MML format
in Wikipedia (http://en.wikipedia.org/wiki/Music_Macro_Language) and in the "Documents"
section of SMW Central (look for custom music tutorials).

   I strongly recommend associating the .mml extension with Notepad/Worpad so you can
edit the .mml files just by double clicking them.


/-/-/-/- What are .m64 and .zseq files? /-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/

    Both .m64 and .zseq are arbritarly file extensions I came up with to designate 
sequence files which follow the specifications used by Mario 64 and Zelda 64. The idea 
is to have a portable format which can be easily shared and inserted in any suitable
ROM. This package only includes a Sequence Inserter for Mario 64, but eventually I
may also release one for the Zelda Debug ROM.

     You can find the most recent specification of the Mario 64 format at my site:
http://sites.google.com/site/messiaen64/mario-64-sequenced-music-specification


/-/-/-/- Custom commands /-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/

    Besides the basic mml syntax, mml2m64 support a few custom commands, most of them
based on Addmusic's implementation.

Global commands (used before channel specific data):
---------------

w = Global volume -> Sets the global volume of your song (min: 1, max 255)

t = Tempo (in BMP) -> Tempo of your song in BPM (min: 1, max: 255)

? = Loop setting -> Use with parameter 0 if you don't want to loop the song.

These global commands can be used as a sort of sequence header. For instance:

?0       ; don't loop song
w200     ; sets global volume to 200
t120     ; sets tempo (BPM) to 120

You can use ';' for comments. Everything after the ; until the newline will be ignored.
If no tempo and volume are specified, default settings will be used. By default, songs
will loop. 

Channel commands:
----------------

# = Begin channel data -> Only use once for each channel. In theory, you can use 
up to 16 channels, but some channels are reserved for Mario sounds, so it's better
to leave some of them free. After the '#', follows the channel number. Channels
are numbered starting from 0 up to 15. Channel #9 (10) is usually used for drums,
like MIDI. 

v = Track volume -> Volume for this channel (min: 1, max: 255)

@ = Instrument number -> Instrument index for this channel. There isn't a master
index of instruments, but a index specific to the sequence you are replacing. For now,
the only way to know what instrument will be used is to experiment. You can try
values between 01 and 20. If you want it to be a drums/percussion channel, use
instrument number 127. If none is specified, a random value is used (from 1 to 8).

k = Gate Time -> This is a custom command specific to mml2m64. In MIDI, gate time is 
the distance between NoteOn and NoteOff events. Use higher values for non-legato and 
staccato and lower values for legato. If none is specified, a default value of 80 
will be used, which usually produces a 'non-legato', but that depends on the instrument
you're using.

Here is an example of channel commands used between blocks of track data (musical 
events) in a .mml file that follows mml2m64 commands:

#0  v120  k20 @1       ; channel 0, volume 120, game time 20 (legato) , instrument 1
d+16d+16r8f16f16r8f+16f+16r8g+16f+16g+16a+1^16      ; track data
;
#9  v150  @127         ; channel 9, volume 150, instrument 127 (drums)
r8<d4d4d4


/-/-/-/- Putting everything together /-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/

    Here is a sample valid .mml file ready to be processed by mml2m64:

--- victory.mml start ---

?0          ; don't loop
w160        ; global volume = 200
t158        ; tempo = 158 BMP

#0  v120  @1
d+16d+16r8f16f16r8f+16f+16r8g+16f+16g+16a+1^16
;
#1  v150  @2
b16b16r8>c+16c+16r8d+16d+16r8f16d+16f16g1^16
;
#2  v120  @3
o2g+16g+16r8a+16a+16r8b16b16r8>c+16<b16>c+16d+1^16
;
#9   v130  @127           ; volume 150, instrument 127 (drums)
r8<d4d4d4;

--- victory.mml end --- 

    Now to turn this into a .m64 file, just run "mml2m64 victory.mml" (or drag
and drop a .mml file into mml2m64 if you are using Windows) and a file called
"victory.mml.m64" will be created. To insert it in the ROM, you'll need to use
the Mario 64 Sequence Inserter. To produce a .zseq file, include the -zelda
argument: "C:\my_mml2m64_dir\mml2m64 victory.mml -zelda".

    You can find a guide showing the usual steps from MIDI to a proper .mml
file in the tutorial.txt file.


/-/-/-/- Mario 64 Sequence Inserter v0.2 (insert_seq.exe) /-/-/-/-/-/-/-/-/-/-/

    After the .m64 is ready, the custom sequence must be inserted in the ROM.
The Sequence Inserter replaces any of the original sequences in an extended
Super Mario 64 ROM with custom music (.m64 files). The new sequence files are 
copied after the original ones, which are keep intact in case you want to revert
(using the m64seq_clean tool).
    The Sequence Inserter is a console program, so you must run it from the
command prompt. 

Usage:

insert_seq <sequence_file> <rom_file> <sequence_number> or <-all>

Example:

insert_seq smb3.m64 mario64.z64 4    (Replaces Inside Castle music with smb3.m64)
insert_seq smb3.m64 mario64.z64 -all (Replaces all sequences with smb3.m64)

-----------------------------
Sequence numbers for Mario 64
-----------------------------

00 - Reserved
01 - End level
02 - SMB music title
03 - Bob-omb's Battlefield
04 - Inside Castle
05 - Dire Dire Docks
06 - Lethal Laval land
07 - Bowser Battle
08 - Snow
09 - Slide
10 - Boo's Haunt
11 - Piranha Plant lullaby
12 - Hazy Maze
13 - Star select
14 - Wing cap
15 - Metal cap
16 - Bowser Message
17 - Bowser course
18 - Collect Star
19 - Ghost Merry-go-round
20 - Start and End Race with Koopa the Quick
21 - Star appears
22 - Boss fight
23 - Take a Key
24 - Looping stairs
25 - Bowser Final Battle
26 - Credits song
27 - ?
28 - Toad
29 - Peach message
30 - Intro Castle sequence
31 - End fanfare
32 - End music
33 - Menu
34 - Lakitu

    Replacing all sequences at once is very useful so you can test how the same
sequence sounds in different instrument sets.
    The custom sequences are saved from 0x7cc6c0 to 0x800000 in the ROM, after
the original sequence bank end and before the first uncompressed MIO0 segment
(in an extended ROM). If you have run out of space, rom m64_seq_clean to clear
all the area between 0x7cc6c0 to 0x800000 and revert the pointers to the original
ones.


/-/-/-/- Troubleshooting /-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/

    So you did everything right but found out there are missing channels, 
instruments out of range and other problems? This section will guide you through
a few possible workarounds. Let me remind you that this is the very first (working)
release of this program, so not everything will work greatly.


1 - One/some of the channels doesn't work.

    Try changing the channel number (# command) or the instrument (@ command). Some 
channels are reserved for Mario sounds, so there might be conflicts. If you replace 
one sequence which is played at the same time as another (ie, Toad's music from 
Inside Castle or the Piranha Plant lullaby) you'll have to make sure they don't use
the same channels.
    I recommend also using the "-all" option of the sequence inserter to find out if
the problem isn't specific to the sequence you are replacing. Alternatively, you can
run m64parser on the original Mario 64 sequences to know which channels each original
sequence is using.


2 - The notes of a specific channel are too low/too high.

    There are two workarounds for this. If you are importing from a MIDI file, you can
use some notation program (such as Finale Notepad) to lower the octaves until you find
an ideal range. Alternatively, you may also work directly with the .mml file. A good way
is to avoid this is to change the initial octave setting. For instance:

    o7 a8 b8 >c4 g4    --> this octave is too high, try changing o7 to o5 or o4.

    <<c16^8 d16 e1     --> to avoid this getting too low, just remove one of the
                           octave lowerews ("<") from the beggining and everything
                           will sound one octave higher.

    Some instruments have more limited ranges than others, so be sure to experiment
also changing instruments.


3 - My Super Mario World .mml file doesn't work very well in mml2m64.

    Although this program is based on Addmusic, there are some differences in the .mml
implementation. Commands such as loops aren't supported yet and channels are handled
a bit differently. Most unsupported commands will be ignored, so there is a good chance
that with some work you can port your SMW .mml to mml2m64. During the initial development
stages of this program, I used .mml files from the Custom Music section of SMW Central 
with varying degrees of success, so you might want to experiment with that also.


4 - The Sequence Inserter won't save the music in the ROM.

    Most likely, you have run out of space. Try running m64seq_clean.exe (just drag and drop 
your ROM there) to erase all the custom sequences. Remember the inserter only works with an
extended Super Mario 64 ROM.



/-/-/-/- Extra tools /-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/-/


Tinymm's octave raisers/lowerers fixer (mml_fix.exe)
---------------------------------------------------

    This program corrects tinymm's (MIDI->MML converter) octave raisers/lowerers
output. It's not required if you are using another program to generate the MML.
A later version shall fix also the channel headers.

Usage: fix_mml [mml_file]  (or just drag and drop a .mml file into mml_fix)

You can download tinymm from SMW Central.


Mario 64 Sequence Cleaner (m64seq_clean.exe)
-------------------------------------------

    This program cleans all the new sequences you inserted in the ROM and restores
the original sequence pointer table.

Usage: m64seq_clean [rom_file]  (or drag and drop an Extended Mario 64 ROM into it)


Mario 64 Sequenced Music Parser (m64parser.exe)
----------------------------------------------

    This tools parses and display all the content of a Mario 64 sequence file. 

Usage: m64parser.exe [file.m64]

    You can save the output by using "m64parser file.m64 > log.txt". The z64parser
is a branch of the parser for .zseq files.


Sequence Bank Ripper (seq_rip.exe)
---------------------------------

    This tool can extract sequence files from Super Mario 64, Mario Kart 64 
and Wave Race 64, if you provide the sequence bank start offset.

Usage: seq_rip.exe [rom] [hex offset]
ie: seq_rip.exe mario_us.z64 0x7B0860

    If the extraction is sucessful, the sequences will be extracted as seq_xx in 
the same directory. You can use a USF rip (http://www.hcs64.com/usf/) as a 
reference for sequence numbering.

Offsets for sequence banks:

Super Mario 64 (US) - 0x7B0860
Mario Kart 64 (US) - 0xBC5F60


Zelda 64 Sequence Ripper (z64seqrip.exe)
---------------------------------------

    This tool extracts sequences from Zelda 64 Debug ROM (and probably Ocarina
of Time/Majora's Mask if you decompress the sequence pointer table).

    It is similar to seq_rip, except that in Zelda the pointer table is separated
from the sequence bank, so you'll have to provide these two offsets.

Usage: z64seqrip.exe [debugrom] [seq_bank_offset] [seq_pointers_offset]
ie: z64seqrip.exe zelootma.z64 0x44DF0 0xBCC6A0

0x44DF0 and 0xBCC6A0 are the offsets in the Debug ROM for the Sequence Bank
and sequence pointer table.